QuickTime For Windows Programmers

Window Records

Because most drawing on the screen takes place in a window, graphics ports are also the basis of the QTML window record (CWindowRecord ). The contents of this structure are fully described in Mac OS For QuickTime Programmers.

The only point to notice here is that its first field (port ) holds not a pointer to a graphics port, but actually a complete graphics port structure embedded directly in the window record. At the machine level, this means that the window record is simply an extended graphics port with some additional, window-specific information appended at the end. In fact, the pointer to a color window (CWindowPtr ) is directly equated to the corresponding graphics port pointer ( CGrafPtr ):



 
typedef   CGrafPtr   CWindowPtr;

This allows a window to be used in place of a graphics port in any context in which a port would be valid. Any QuickDraw routine that expects a pointer to a graphics port as a parameter will accept a window pointer in its place, since the two pointers are really the same data type. In particular, the QuickTime routines can pass your window pointer to the MacSetPort function discussed in the preceding section, making the window the current port in which to display the contents of a movie.

On the Windows platform, however, your window is normally designated by a Windows-style handle (HWND ) rather than a QTML pointer (CWindowPtr ). To allow QuickTime to draw into the window, you must first register it with QTML by calling the QTML routine CreatePortAssociation :



 
void

    CreatePortAssociation

        (void  *theWnd,

         Ptr    storage

         long   flags);

This creates a graphics port and associates it with this window in an internal data structure maintained by QTML. The first parameter (theWnd ) is your Windows-style window handle, of type HWND . The second parameter (storage ) allows you to supply your own storage for the CGrafPort record, if you wish. Generally, you will always pass nil , allowing the call to allocate memory. (If you leave this parameter null, QTML will allocate the space for you.)

Typically, you'll want to register your movie window at the time it is created by calling CreatePortAssociation from your window procedure in response to the WM_CREATE message, as shown in Listing 3 .

Listing 3 Creating a port association



 
LRESULT

    CALLBACK WinProc

        (HWND     thisWindow,                       // Handle to window

         UINT     msgType,                          // Message type

         WPARAM   wParam,                           // Message-dependent parameter

         LPARAM   lParam)                           // Message-dependent parameter



    {   

            ·

            ·

        

        switch ( msgType )

            {   

                case WM_CREATE:

                    CreatePortAssociation (thisWindow, NULL);

                                                        // Register window with QTML

                    break;

                

                        ·

                        ·

                

            }  /* end switch ( msgType ) */

        

    }  /* end WinProc */

Once you've registered your window, you can use the conversion routine GetHWNDPort to obtain a QTML-style window pointer for it:



 
WindowPtr 

    GetNativeWindowPort 

        (void  *h)

There's also a reverse conversion function for recovering the window handle associated with a given window pointer:



 
void* 

    GetPortNativeWindow 

        (WindowPtr   wptr)

When you're through with a particular window, you can deregister it and dispose of its graphics port with DestroyPortAssociation :



 
void 

    DestroyPortAssociation 

        (CGrafPtr    cgp)

A good place to do this is in your window procedure's response to the WM_CLOSE or WM_DESTROY message. Listing 4 shows an example.

Listing 4 Destroying a port association



 
LRESULT

    CALLBACK WinProc

        (HWND     thisWindow,                       // Handle to window

         UINT     msgType,                          // Message type

         WPARAM   wParam,                           // Message-dependent parameter

         LPARAM   lParam)                           // Message-dependent parameter



    {   

                ·

                ·

        

        switch ( msgType )

            {   

                case WM_CLOSE:

                    CWindowPtr   qtmlPtr;               // Macintosh window pointer

                    

                    qtmlPtr = GetHWNDPort(thisWindow);  // Convert to window pointer

                    DestroyPortAssociation (qtmlPtr);   // Deregister window

                    break;

                

                        ·

                        ·

                

            }  /* end switch ( msgType ) */

        

                ·

                ·

        

    }  /* end WinProc */